home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / rpm / hdrinline.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-10-22  |  12.8 KB  |  512 lines
  1. /*@-type@*/ /* FIX: cast to HV_t bogus */
  2. #ifndef H_HDRINLINE
  3. #define H_HDRINLINE
  4.  
  5. /** \ingroup header
  6.  * \file rpmdb/hdrinline.h
  7.  */
  8.  
  9. #ifdef __cplusplus
  10. extern "C" {
  11. #endif
  12. /*@+voidabstract -nullpass -mustmod -compdef -shadow -predboolothers @*/
  13.  
  14. /** \ingroup header
  15.  * Header methods for rpm headers.
  16.  */
  17. /*@observer@*/ /*@unchecked@*/
  18. extern struct HV_s * hdrVec;
  19.  
  20. /** \ingroup header
  21.  */
  22. /*@unused@*/ static inline HV_t h2hv(Header h)
  23.     /*@*/
  24. {
  25.     /*@-abstract -castexpose -refcounttrans@*/
  26.     return ((HV_t)h);
  27.     /*@=abstract =castexpose =refcounttrans@*/
  28. }
  29.  
  30. /** \ingroup header
  31.  * Create new (empty) header instance.
  32.  * @return        header
  33.  */
  34. /*@unused@*/ static inline
  35. Header headerNew(void)
  36.     /*@*/
  37. {
  38.     return hdrVec->hdrnew();
  39. }
  40.  
  41. /** \ingroup header
  42.  * Dereference a header instance.
  43.  * @param h        header
  44.  * @return        NULL always
  45.  */
  46. /*@unused@*/ static inline
  47. /*@null@*/ Header headerFree( /*@killref@*/ /*@null@*/ Header h)
  48.     /*@modifies h @*/
  49. {
  50.     /*@-abstract@*/
  51.     if (h == NULL) return NULL;
  52.     /*@=abstract@*/
  53.     return (h2hv(h)->hdrfree) (h);
  54. }
  55.  
  56. /** \ingroup header
  57.  * Reference a header instance.
  58.  * @param h        header
  59.  * @return        new header reference
  60.  */
  61. /*@unused@*/ static inline
  62. Header headerLink(Header h)
  63.     /*@modifies h @*/
  64. {
  65.     return (h2hv(h)->hdrlink) (h);
  66. }
  67.  
  68. /** \ingroup header
  69.  * Dereference a header instance.
  70.  * @param h        header
  71.  * @return        new header reference
  72.  */
  73. /*@unused@*/ static inline
  74. Header headerUnlink(/*@killref@*/ /*@null@*/ Header h)
  75.     /*@modifies h @*/
  76. {
  77.     /*@-abstract@*/
  78.     if (h == NULL) return NULL;
  79.     /*@=abstract@*/
  80.     return (h2hv(h)->hdrunlink) (h);
  81. }
  82.  
  83. /*@-exportlocal@*/
  84. /** \ingroup header
  85.  * Sort tags in header.
  86.  * @param h        header
  87.  */
  88. /*@unused@*/ static inline
  89. void headerSort(Header h)
  90.     /*@modifies h @*/
  91. {
  92. /*@-noeffectuncon@*/ /* FIX: add rc */
  93.     (h2hv(h)->hdrsort) (h);
  94. /*@=noeffectuncon@*/
  95.     return;
  96. }
  97.  
  98. /** \ingroup header
  99.  * Restore tags in header to original ordering.
  100.  * @param h        header
  101.  */
  102. /*@unused@*/ static inline
  103. void headerUnsort(Header h)
  104.     /*@modifies h @*/
  105. {
  106. /*@-noeffectuncon@*/ /* FIX: add rc */
  107.     (h2hv(h)->hdrunsort) (h);
  108. /*@=noeffectuncon@*/
  109.     return;
  110. }
  111. /*@=exportlocal@*/
  112.  
  113. /** \ingroup header
  114.  * Return size of on-disk header representation in bytes.
  115.  * @param h        header
  116.  * @param magicp    include size of 8 bytes for (magic, 0)?
  117.  * @return        size of on-disk header
  118.  */
  119. /*@unused@*/ static inline
  120. unsigned int headerSizeof(/*@null@*/ Header h, enum hMagic magicp)
  121.     /*@modifies h @*/
  122. {
  123.     /*@-abstract@*/
  124.     if (h == NULL) return 0;
  125.     /*@=abstract@*/
  126.     return (h2hv(h)->hdrsizeof) (h, magicp);
  127. }
  128.  
  129. /** \ingroup header
  130.  * Convert header to on-disk representation.
  131.  * @param h        header (with pointers)
  132.  * @return        on-disk header blob (i.e. with offsets)
  133.  */
  134. /*@unused@*/ static inline
  135. /*@only@*/ /*@null@*/ void * headerUnload(Header h)
  136.     /*@modifies h @*/
  137. {
  138.     return (h2hv(h)->hdrunload) (h);
  139. }
  140.  
  141. /** \ingroup header
  142.  * Convert header to on-disk representation, and then reload.
  143.  * This is used to insure that all header data is in one chunk.
  144.  * @param h        header (with pointers)
  145.  * @param tag        region tag
  146.  * @return        on-disk header (with offsets)
  147.  */
  148. /*@unused@*/ static inline
  149. /*@null@*/ Header headerReload(/*@only@*/ Header h, int tag)
  150.     /*@modifies h @*/
  151. {
  152.     /*@-onlytrans@*/
  153.     return (h2hv(h)->hdrreload) (h, tag);
  154.     /*@=onlytrans@*/
  155. }
  156.  
  157. /** \ingroup header
  158.  * Duplicate a header.
  159.  * @param h        header
  160.  * @return        new header instance
  161.  */
  162. /*@unused@*/ static inline
  163. /*@null@*/ Header headerCopy(Header h)
  164.     /*@modifies h @*/
  165. {
  166.     return (h2hv(h)->hdrcopy) (h);
  167. }
  168.  
  169. /** \ingroup header
  170.  * Convert header to in-memory representation.
  171.  * @param uh        on-disk header blob (i.e. with offsets)
  172.  * @return        header
  173.  */
  174. /*@unused@*/ static inline
  175. /*@null@*/ Header headerLoad(/*@kept@*/ void * uh)
  176.     /*@modifies uh @*/
  177. {
  178.     return hdrVec->hdrload(uh);
  179. }
  180.  
  181. /** \ingroup header
  182.  * Make a copy and convert header to in-memory representation.
  183.  * @param uh        on-disk header blob (i.e. with offsets)
  184.  * @return        header
  185.  */
  186. /*@unused@*/ static inline
  187. /*@null@*/ Header headerCopyLoad(const void * uh)
  188.     /*@*/
  189. {
  190.     return hdrVec->hdrcopyload(uh);
  191. }
  192.  
  193. /** \ingroup header
  194.  * Read (and load) header from file handle.
  195.  * @param fd        file handle
  196.  * @param magicp    read (and verify) 8 bytes of (magic, 0)?
  197.  * @return        header (or NULL on error)
  198.  */
  199. /*@unused@*/ static inline
  200. /*@null@*/ Header headerRead(FD_t fd, enum hMagic magicp)
  201.     /*@modifies fd @*/
  202. {
  203.     return hdrVec->hdrread(fd, magicp);
  204. }
  205.  
  206. /** \ingroup header
  207.  * Write (with unload) header to file handle.
  208.  * @param fd        file handle
  209.  * @param h        header
  210.  * @param magicp    prefix write with 8 bytes of (magic, 0)?
  211.  * @return        0 on success, 1 on error
  212.  */
  213. /*@unused@*/ static inline
  214. int headerWrite(FD_t fd, /*@null@*/ Header h, enum hMagic magicp)
  215.     /*@modifies fd, h @*/
  216. {
  217.     /*@-abstract@*/
  218.     if (h == NULL) return 0;
  219.     /*@=abstract@*/
  220.     return (h2hv(h)->hdrwrite) (fd, h, magicp);
  221. }
  222.  
  223. /** \ingroup header
  224.  * Check if tag is in header.
  225.  * @param h        header
  226.  * @param tag        tag
  227.  * @return        1 on success, 0 on failure
  228.  */
  229. /*@unused@*/ static inline
  230. int headerIsEntry(/*@null@*/ Header h, int_32 tag)
  231.     /*@modifies h @*/
  232. {
  233.     /*@-abstract@*/
  234.     if (h == NULL) return 0;
  235.     /*@=abstract@*/
  236.     return (h2hv(h)->hdrisentry) (h, tag);
  237. }
  238.  
  239. /** \ingroup header
  240.  * Free data allocated when retrieved from header.
  241.  * @param h        header
  242.  * @param data        pointer to tag value(s)
  243.  * @param type        type of data (or -1 to force free)
  244.  * @return        NULL always
  245.  */
  246. /*@unused@*/ static inline
  247. /*@null@*/ void * headerFreeTag(Header h,
  248.         /*@only@*/ /*@null@*/ const void * data, rpmTagType type)
  249.     /*@modifies data @*/
  250. {
  251.     return (h2hv(h)->hdrfreetag) (h, data, type);
  252. }
  253.  
  254. /** \ingroup header
  255.  * Retrieve tag value.
  256.  * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
  257.  * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
  258.  * entry is present).
  259.  *
  260.  * @param h        header
  261.  * @param tag        tag
  262.  * @retval *type    tag value data type (or NULL)
  263.  * @retval *p        pointer to tag value(s) (or NULL)
  264.  * @retval *c        number of values (or NULL)
  265.  * @return        1 on success, 0 on failure
  266.  */
  267. /*@unused@*/ static inline
  268. int headerGetEntry(Header h, int_32 tag,
  269.             /*@null@*/ /*@out@*/ hTYP_t type,
  270.             /*@null@*/ /*@out@*/ void ** p,
  271.             /*@null@*/ /*@out@*/ hCNT_t c)
  272.     /*@modifies *type, *p, *c @*/
  273. {
  274.     return (h2hv(h)->hdrget) (h, tag, type, p, c);
  275. }
  276.  
  277. /** \ingroup header
  278.  * Retrieve tag value using header internal array.
  279.  * Get an entry using as little extra RAM as possible to return the tag value.
  280.  * This is only an issue for RPM_STRING_ARRAY_TYPE.
  281.  *
  282.  * @param h        header
  283.  * @param tag        tag
  284.  * @retval *type    tag value data type (or NULL)
  285.  * @retval *p        pointer to tag value(s) (or NULL)
  286.  * @retval *c        number of values (or NULL)
  287.  * @return        1 on success, 0 on failure
  288.  */
  289. /*@unused@*/ static inline
  290. int headerGetEntryMinMemory(Header h, int_32 tag,
  291.             /*@null@*/ /*@out@*/ hTYP_t type,
  292.             /*@null@*/ /*@out@*/ hPTR_t * p, 
  293.             /*@null@*/ /*@out@*/ hCNT_t c)
  294.     /*@modifies *type, *p, *c @*/
  295. {
  296.     return (h2hv(h)->hdrgetmin) (h, tag, type, p, c);
  297. }
  298.  
  299. /** \ingroup header
  300.  * Add tag to header.
  301.  * Duplicate tags are okay, but only defined for iteration (with the
  302.  * exceptions noted below). While you are allowed to add i18n string
  303.  * arrays through this function, you probably don't mean to. See
  304.  * headerAddI18NString() instead.
  305.  *
  306.  * @param h        header
  307.  * @param tag        tag
  308.  * @param type        tag value data type
  309.  * @param p        pointer to tag value(s)
  310.  * @param c        number of values
  311.  * @return        1 on success, 0 on failure
  312.  */
  313. /*@mayexit@*/
  314. /*@unused@*/ static inline
  315. int headerAddEntry(Header h, int_32 tag, int_32 type, const void * p, int_32 c)
  316.     /*@modifies h @*/
  317. {
  318.     return (h2hv(h)->hdradd) (h, tag, type, p, c);
  319. }
  320.  
  321. /** \ingroup header
  322.  * Append element to tag array in header.
  323.  * Appends item p to entry w/ tag and type as passed. Won't work on
  324.  * RPM_STRING_TYPE. Any pointers into header memory returned from
  325.  * headerGetEntryMinMemory() for this entry are invalid after this
  326.  * call has been made!
  327.  *
  328.  * @param h        header
  329.  * @param tag        tag
  330.  * @param type        tag value data type
  331.  * @param p        pointer to tag value(s)
  332.  * @param c        number of values
  333.  * @return        1 on success, 0 on failure
  334.  */
  335. /*@unused@*/ static inline
  336. int headerAppendEntry(Header h, int_32 tag, int_32 type,
  337.         const void * p, int_32 c)
  338.     /*@modifies h @*/
  339. {
  340.     return (h2hv(h)->hdrappend) (h, tag, type, p, c);
  341. }
  342.  
  343. /** \ingroup header
  344.  * Add or append element to tag array in header.
  345.  * @todo Arg "p" should have const.
  346.  * @param h        header
  347.  * @param tag        tag
  348.  * @param type        tag value data type
  349.  * @param p        pointer to tag value(s)
  350.  * @param c        number of values
  351.  * @return        1 on success, 0 on failure
  352.  */
  353. /*@unused@*/ static inline
  354. int headerAddOrAppendEntry(Header h, int_32 tag, int_32 type,
  355.         const void * p, int_32 c)
  356.     /*@modifies h @*/
  357. {
  358.     return (h2hv(h)->hdraddorappend) (h, tag, type, p, c);
  359. }
  360.  
  361. /** \ingroup header
  362.  * Add locale specific tag to header.
  363.  * A NULL lang is interpreted as the C locale. Here are the rules:
  364.  * \verbatim
  365.  *    - If the tag isn't in the header, it's added with the passed string
  366.  *       as new value.
  367.  *    - If the tag occurs multiple times in entry, which tag is affected
  368.  *       by the operation is undefined.
  369.  *    - If the tag is in the header w/ this language, the entry is
  370.  *       *replaced* (like headerModifyEntry()).
  371.  * \endverbatim
  372.  * This function is intended to just "do the right thing". If you need
  373.  * more fine grained control use headerAddEntry() and headerModifyEntry().
  374.  *
  375.  * @param h        header
  376.  * @param tag        tag
  377.  * @param string    tag value
  378.  * @param lang        locale
  379.  * @return        1 on success, 0 on failure
  380.  */
  381. /*@unused@*/ static inline
  382. int headerAddI18NString(Header h, int_32 tag, const char * string,
  383.         const char * lang)
  384.     /*@modifies h @*/
  385. {
  386.     return (h2hv(h)->hdraddi18n) (h, tag, string, lang);
  387. }
  388.  
  389. /** \ingroup header
  390.  * Modify tag in header.
  391.  * If there are multiple entries with this tag, the first one gets replaced.
  392.  * @param h        header
  393.  * @param tag        tag
  394.  * @param type        tag value data type
  395.  * @param p        pointer to tag value(s)
  396.  * @param c        number of values
  397.  * @return        1 on success, 0 on failure
  398.  */
  399. /*@unused@*/ static inline
  400. int headerModifyEntry(Header h, int_32 tag, int_32 type,
  401.             const void * p, int_32 c)
  402.     /*@modifies h @*/
  403. {
  404.     return (h2hv(h)->hdrmodify) (h, tag, type, p, c);
  405. }
  406.  
  407. /** \ingroup header
  408.  * Delete tag in header.
  409.  * Removes all entries of type tag from the header, returns 1 if none were
  410.  * found.
  411.  *
  412.  * @param h        header
  413.  * @param tag        tag
  414.  * @return        0 on success, 1 on failure (INCONSISTENT)
  415.  */
  416. /*@unused@*/ static inline
  417. int headerRemoveEntry(Header h, int_32 tag)
  418.     /*@modifies h @*/
  419. {
  420.     return (h2hv(h)->hdrremove) (h, tag);
  421. }
  422.  
  423. /** \ingroup header
  424.  * Return formatted output string from header tags.
  425.  * The returned string must be free()d.
  426.  *
  427.  * @param h        header
  428.  * @param fmt        format to use
  429.  * @param tbltags    array of tag name/value pairs
  430.  * @param extensions    chained table of formatting extensions.
  431.  * @retval errmsg    error message (if any)
  432.  * @return        formatted output string (malloc'ed)
  433.  */
  434. /*@unused@*/ static inline
  435. /*@only@*/ char * headerSprintf(Header h, const char * fmt,
  436.              const struct headerTagTableEntry_s * tbltags,
  437.              const struct headerSprintfExtension_s * extensions,
  438.              /*@null@*/ /*@out@*/ errmsg_t * errmsg)
  439.     /*@modifies *errmsg @*/
  440. {
  441.     return (h2hv(h)->hdrsprintf) (h, fmt, tbltags, extensions, errmsg);
  442. }
  443.  
  444. /** \ingroup header
  445.  * Duplicate tag values from one header into another.
  446.  * @param headerFrom    source header
  447.  * @param headerTo    destination header
  448.  * @param tagstocopy    array of tags that are copied
  449.  */
  450. /*@unused@*/ static inline
  451. void headerCopyTags(Header headerFrom, Header headerTo, hTAG_t tagstocopy)
  452.     /*@modifies headerFrom, headerTo @*/
  453. {
  454. /*@-noeffectuncon@*/ /* FIX: add rc */
  455.     hdrVec->hdrcopytags(headerFrom, headerTo, tagstocopy);
  456. /*@=noeffectuncon@*/
  457.     return;
  458. }
  459.  
  460. /** \ingroup header
  461.  * Destroy header tag iterator.
  462.  * @param hi        header tag iterator
  463.  * @return        NULL always
  464.  */
  465. /*@unused@*/ static inline
  466. HeaderIterator headerFreeIterator(/*@only@*/ HeaderIterator hi)
  467.     /*@modifies hi @*/
  468. {
  469.     return hdrVec->hdrfreeiter(hi);
  470. }
  471.  
  472. /** \ingroup header
  473.  * Create header tag iterator.
  474.  * @param h        header
  475.  * @return        header tag iterator
  476.  */
  477. /*@unused@*/ static inline
  478. HeaderIterator headerInitIterator(Header h)
  479.     /*@modifies h */
  480. {
  481.     return hdrVec->hdrinititer(h);
  482. }
  483.  
  484. /** \ingroup header
  485.  * Return next tag from header.
  486.  * @param hi        header tag iterator
  487.  * @retval *tag        tag
  488.  * @retval *type    tag value data type
  489.  * @retval *p        pointer to tag value(s)
  490.  * @retval *c        number of values
  491.  * @return        1 on success, 0 on failure
  492.  */
  493. /*@unused@*/ static inline
  494. int headerNextIterator(HeaderIterator hi,
  495.         /*@null@*/ /*@out@*/ hTAG_t tag,
  496.         /*@null@*/ /*@out@*/ hTYP_t type,
  497.         /*@null@*/ /*@out@*/ hPTR_t * p,
  498.         /*@null@*/ /*@out@*/ hCNT_t c)
  499.     /*@modifies hi, *tag, *type, *p, *c @*/
  500. {
  501.     return hdrVec->hdrnextiter(hi, tag, type, p, c);
  502. }
  503.  
  504. /*@=voidabstract =nullpass =mustmod =compdef =shadow =predboolothers @*/
  505.  
  506. #ifdef __cplusplus
  507. }
  508. #endif
  509.  
  510. #endif    /* H_HDRINLINE */
  511. /*@=type@*/
  512.